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Indian Standard
GUIDELINES FOR THE DOCUMENTATION OF COMPUTER-BASED APPLICATION SYSTEMS FOR INFORMATION PROCESSING
NATIONAL FOREWORD

This Indian Standard which is identical with IS0 6592 : 1985 `Information processing Guidelines for the documentation of computer-based application systems' issued by the International Organization for Standardization ( IS0 ) was adopted by the Bureau of Indian Standards on the recommendation of Information Systems and Software Sectional Committee ( LTD 33 ) and approval of the Electronics and Telecommunication Division Council. In the adopted standard certain terminology and conventions are however not identical used in Indian Standards. Attention is particularly drawn to the following: Wherever the words `International Standard' should be read as `Indian Standard'. appear referring to those

to this standard, they

1
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1

Scope and field of application

This International Standard establishes guidelines for the
documentation of computer-based application systems. lt also contains checklists with the aim of supporting effective activities throughout the system life cycle. The guidelines given in this International Standard have been developed with the aim of a) obtaining the necessary commitment of the parties involved with the development of the computer-based application system; b) contributing to the production of a well-planned, standardized system documentation; c) enabling the successive production of system documentation in parallel with system development. Well-defined rules for documentation during the process of system development will facilitate a) the preparation of the documentation itself;

This International Standard does not cover the requirements for documenting the hardware design of a compcter-based application system.

2
2.1

Principles

of documentation

General considerations

Despite the diversity of applications of computer-based systems, there are fundamental similarities, for example, the obvious feature that a computer is always subject to input, processing and output phases. There should always be a need to establish and justify the resources such as personnel, materials and finance necessary to develop and implement a computer project, however large or small, and to document adequately all aspects of the proposed system. It is in this context that the guidelines established in this International Standard have been formulated; the aim being to establish a basic framework of documentation that would act as a solid base for any project and enable effective development and implementation through proper progress and control machinery, permitting the development to proceed in a planned and authorized manner. The application of these recommendations will vary according to the type of system being introduced: as an example, methods of operating might assume greater importance in a process control environment than in, for example, a commercial batch processing system. A particular document or piece of information may have no relevance to one system and vet be important to another. The checklists given in this International Standard should be used to ensure that, if information is omitted from the documentation, the omission is the result of a positive decision and not an oversight. The gradual change in the level of detail in the development process may necessitate revision of documentation from earlier stages.

b) estimation of the time and resources required for the achievement of a project; c) exchange of information between the parties concerned, resulting in selection of attainable objectives for a system;

a more complete and well-considered functional design; d) making decisions and briefing of personnel during work on system development. The system documentation produced in accordance with these guidelines a) enables the management to exercise control over the development process; b) enables users of the system to use it efficiently and correctly; c) enables computer operators to schedule and run the system ; d) aids diagnosis and correction of errors or faults;

2.2

Types of information

Two basic types of information are identified in this International Standard, i.e. administrative and technical. Administrative information is project control and management information which records what has been atthorized and what has been done. This information should be retained but it may not be necessary to update it once implementation is complete.

e) provides information about the system as support for system maintenance.
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Technical information includes an up-to-date description of all aspects of the system, including hardware, software, and data. It is essential that it is constantly updated during the system life cycle. Both types of information may be included in some documents, but these guidelines recommend that they be kept in separate sections so that the technical information may be more easily maintained.

3.3.2 a)

System problem and information system problems:

analysis:

1) definition, including background and present situation ; 2) b) constraints, technical and financial;

system objectives: 1) 2) 3) definition and description; delimitation; summary;

2.3 Relationship between project stages and documentation
The guidelines given in this International Standard are structured to relate project development stages to the documentation which they generate. Generally, each stage is initiated and concluded by a document. Although the main stages take place in sequence, some stages and the preparation of some documents overlap each other, for example preparation of system support manuals should be started during the system design and development stage. The number of stages and the number of documents may vary for different applications; these guidelines list the elements of documentation which would usually appear in the documents generated by each stage of the development process.

c)

system information :

1) definition and description;
2) 3) d) relations; specifications;

system processing : 1) 2) 3) description; input, stored data, and output; relations between data; periodicity; volume of data. and requirements:

3
3.1

Feasibility study Objectives
3.3.3 following a a) bl c) d) e)

4) 5)

The objectives of the feasibility study are a) to identify exactly preliminary study; what is needed

Project organization staff requirements;

b) to work out possible solutions and identify a preferred solution; c) to document the requirements and constraints for the new system.

training and education; timetable of main activities; manpower; hardware; software; accommodation. Costs and benefits: financial costs; benefits. Proposed system : functional description; controls to ensure accuracy; security; interfaces; data flow;

3.2

Feasibility study request

f) g) 3.3.4 a) bl 3.3.5 a)

This document authorizes the use of resources to investigate a specific requirement, design aim or problem and to suggest a possible solution. It is produced by or for the user before work commences on the project. Prepamiion of this document may entail the assistance of a specialist in determining, for example, the time and cost targets for the feasibility study. Authorization of this feasibility study request leads to a feasibility study and the writing of a feasibility study report.

3.3
3.3.1

Feasibility study report Objective

b) cl d)

The feasibility study report should enable the user to decide whether or not to continue to the next stage of system design.

e)
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Stages

and the

Documents Feasibility

produced

Feasibility study (see clause 3)

4

1 W

study request

Feasibility study report

System

design study

System design study request (see 4.2)

(see clause 4)

I
1 System design and development (see clause 5)

System design study report (see 4.31

I

r

t

e
System design documentation general system and component documentation (see 5.3, 5.4 and annexes A, 6 and C) Implementation documentation plan and tests (see 7.2.1

:

:

System

support

and 7.2.2)

(see clause 6)

1
System support

I

documentation

:

user, operations,

Post implementation reviews (see clause 8)

Evaluation lsce 8.21

rfyorts

c

Alternative

starting points in cases where

a separate feasibility

study IS not required

Figure

-

Summary

of the relationship

between

project

development

5
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f) 9) h) j) k) m)

allcwance

for growth:

volume of data,

new functions;

4.2

System

design

study

request

scheduling/timing; non-computer manpower; hardware; software; accomodation. functions;

This document taken after simplest form,

states the action that the initiator requires to be the feasibility accept study report. In its in it will merely the recommendations

considering

this report and authorize

the system design study.

4.3

System

design

study

report

n)

4.3.1

Objectives
detailed

3.3.6

implementation, . _ considerations : a) b) c) d) e)
f) 9) h) j) k) system testing;

quality and acceptance

The system design study report should be sufficiently in order that a) etc. the user has a clear description processing, output

of what the system will stored, timing,

file creation/conversion; integration with existing systems;

do (input,

information

1;
the user knows exactly what to do to operate the

b) user education emulation; proposed changeover methods; and training;

system

;
changes or adaptations tasks; for the system are sufnecessary to and can be

c)

the organizational

implement commenced d)

the system and operate it are defined, as separate

modifications

to service; requirements;

the functional

requirements

quality assurance product

ficiently unambiguous to be worked

for the system design documentation

out in the next phase.

liability requirements; criteria. 4.3.2 a)

system acceptance

Plans :
organization; timetable; major resource requirements;

3.3.7
a) b) c)

Support recovery

facilities: bl from failure; cl

maintenance; d) availability of spares. e) standards to be used. quality assurance;

3.3.8 3.3.9 a)

Glossary:

explanation

of new or unusual terms. 4.3.3 Costs

and benefits:
costs; costs; costs;

Conclusions

and recommendations:

a) b) c) d) e)

development installation

system requirements 1) 2) needs of the user;

:

training and education running costs; benefits, tangible

how they will be met.

b)

alternatives 1) 2) describe

:
alternatives considered;

and intangible.

4.3.4 a) b)

System description :
functional hardware overview of the application of the system;

state reasons for rejection.

requirements; for example . terminals

4
4.1

System

aesign study

requirements, c) communication lines, modems, concentrators: d) software requirements operating system, etc. ; in detail, the chosen e) data description for

Objective
of this stage is to define,

languages,

data

base

The objective design.

;

6
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f)

data flow,

including

the normal and maximum

volume

5) 6)

financial security;

estimates;

of data; g) h) j) allowance for change in data volume; of the data; protection, physical .:

7) d)

scheduling/timing;

controls to ensure the accuracy security, system integrity, data

glossary of new or unusual terms used.

security, k)

availability; and power requirements (including any

4.3.6 a) b)

Summary manpower; hardware;

for management:

environmental

stand-by m)

arrangements)

;
either existing or pro-

interfaces

with other systems,

cl d)

quality assurance accommodation cost estimates:

requirements; requirements;

Dosed n) P) 4)

;
requirements; for additional functions;

scheduling allowance

e)

1) next stage of project;
2) f) total project;

non-computer

procedures.

benefit estimates ; timetable.

43.5 a) b) c) d) e) f1 g) h) j) k)

implementation,

quality

and acceptance

plans:

g)

user education/training; file creation/conversion; systern testing and performance emulation assessments; 5.1 Objectives are as follows: in detail, automated and manual processing

5

System

design

and development

;
to service;

modifications integration changeover

The objectives a) specify,

with existing systems; methods; requirements;

procedures b) produce

and establish their boundaries; documentation to enable the writing of pro-

grams: quality assurance extent of product c) liability; criteria. provide the information necessary to cam/ out work on of the new system; in

testing and implementation d)

system acceptance

make a detailed plan of all activities to be performed stage; to the preparation

the implementation 4.3.6 a) bl
Cl

Support

facilities:

e)

give consideration

of system support

manuals. recovery from failures; responsibility availability and liability for maintenance;

5.2

System design documentation
of this documentation is to provide a complete principles whtch

of spares and back-up.

The purpose

design record of the system based on the following 4.3.7 a) b1 c) Summary problem of application definition system

:
a) that every part of the system has a function should be described bl

and solution;

;
of a complete system can be fully

recommendation system operation 1) 2) 3) 41 manpower;

; ;

that all the functions

described by breaking the system down into its suhordin,!te parts and also by describing these and their interitctrons and relationships. The documentation should normally contain at least two Ievt++ 9 (see 5.3). lsee 5.4).

hardware: software; accommodation

of detail, namely: general system documentatton and component documentation

;
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5.3

General

system

documentation
the level of detail of which the depends on the requirements of may be required to form the

6.2

System

support

documentation
should be formed from documents stage. that during

In the general documentation, system should be described the system. This documentation

Support produced Any

documentation during made

the system

design and development produced

changes

to the documents

basis for system support

manuals. should detail

stage should be reflected in the documents What

for system support.

The general system documentation a) b) cl project title; objectives; description (both textual

is actually provided will depend on the particular system maintenance policy and documentation be provided stanunder in order to meet the system support objective that the documentation

requirements, dards. However,

it is recommended and diagrammatic)

;

the following a) User

headings: manual in a clear and concise way, the rights

d) e) f) 9) h) j) k) m)

identification interfaces security;

of subsystems;

with other systems; This should describe, and responsibilities system. The following are examples of what these riqhts and of both the user and the supplier of the

controls operating recovery support

(including

audit requirements);

environment; from failure; facilities necessary to operate the system;

responsibilities 1) -

may be:

The rights of the user may include: the right to information about the usage of the

data requirements; tesi procedures; change procedures.

system

;
about the system results

-

the right to information

and the correction 2) specifications of proThe responsibilities

of errors in data. of the user may include: of input data; in

5.4

Component

documentation
should give detailed manuals.

This documentation

the correct preparation informing

grams, files and manual operations. the basis for system support

It may be required to form the supplier of any errors detected the system.

54.1

Program specification

3) -

The rights of the supplier may include: the right to revise the system, the right to perform continuous as supplied; testing to ensure correctly.

See annex A.
5.4.2 File and database B. 4) 5.4.3 Manual routines specification specification

-

that the system continues See annex The responsiblities the maintenance

to function

of the supplier may include: of accurate and up-to-date

See annex C.

documentation; the distribution of accumulated user experience

with the system.

6
6.1

System Objective

support
All these rights and responsibilities ment between fluenced standards. by national Information will be subject to agreeand may be inand/or on aspects legislation the supplier and the customer and international applicable

The objective been accepted a) b) c)

of this stage is to support the system once it has by the user. It embraces the following aspects:

to legislation

of quality assurance and product liability should be included in this manual.

normal use of the system; detection and correction of errors; b) Operations manual . how to operate equipment

possible modifications

and enhancements. This should describe computer modes.

the system using the in all its operational

It should be understood

that this activity may not be carried out the system.

and associated

by the same staff who developed

8
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c)

Program
should

manuals
describe the purpose of each program formulae with and timing. and and They

f) g) h) j)

verification

of maintenance

procedures;

These provide should results.

timing and method system changeover recovery procedures

of implementation; procedures;

information include

such

as mathematical facilities

algorithms

used, error handling listings

of the program,

comments,

useful for modifications

and enhancements,

test data and

d)

Data manual
down to the

7.2.2

Acceptance

tests should specify how the tests will be con environments. It should and give

This should describe the system data structure level of detail specified by system requirements.

The documentation

ducted within the defined tolerances where

operational

also provide a check list of the results to be expected necessary.

e)

System

technical

manual
the way the Where descrip7.2.3 Acceptance report embodying the results of the accepto all relevant authorities.

This should enable technical staff to understand system works, assist them in error detection and tions. in making modifications appropriate, it should make reference

and correction This should be a document tance tests signed by and duplicated If acceptance

and enhancements. to hardware

is to be qualified in any way, an official statement and suggested remedies, if possible, should be

f)

System change record
when, how, why and by whom to any part of the

of deficiencies orovided.

This should record what, changes system. were made and

authorized

8 7 7.1 System implementation

Post implementation

reviews

8.1

Objectives
of this stage are periodically the system's fulfilment to of objectives; and the cost

Objective
of this stage is to carry out full acceptance that all the specified requirements tests

The objectives a) b)

The objective

investigate follow

of the system under all aspects of its operational and demonstrate met.

environment have been up the distribution of resources

estimates;

7.2

Documentation

requirements
to this stage should consist of an

c)

specify

the intangible

positive and negative

effects

of

the system; The input documentation implementation tance report. The output documentation plan and the acceptance tests for the system. d) analyse and record the experience gained during work

from this stage should be an accep-

on the systems development.

8.2
7.2.1 Implementation implementation planning plan takes place at the end of project during the development

Evaluation
reports

reports

Although

Evaluation a)

development, of the system.

should begin at an early stage and the as necessary

plan should be updated

assess whether

the original system objectives were cor-

rect and how far they have been met in practice; b) pinpoint matters capable of improvements;

The plan should detail. for example:

a) b) c) d) e)

accommodation staff organization; user education file set up:

and environment;

c) d)

endorse good practices; identify and assess operational problems encountered,

if any; e) f) state whether document the * the claimed benefits have been achieved: experiences projects. which will assist future

and training;

update, assembly and distribution of documents;

systems development
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9
9.1

Management

of documents

It is recommended that a loose-leaf format is adopted.
Procedures to be followed for amendments to the system documentation should be agreed and clearly defined. It is essential that all project staff and users be acquainted with the correct procedures.

Production and handling of documents

An important aspect of all work on documentation is the creation of documents to fulfil the needs of the user of the documents. It is essential that such needs be clearlv defined and that the content of a document be presented in a manner which makes it easy for the reader to access and understand. Each individual document created in conjunction with a stage in the system development shall be allocated a unique identification number or code to facilitate its storage and subsequent retrieval. The identifying number or code shall clearly show the system or project and category of documentation to which the document belongs. The principles governing the identification of systems and subsystems may vary ,from organization to organization but should be described in the indivrdual company's own instructions. It is vital for ease of reference and control of amendments or updates that a clear and unambiguous method of page referencing be adopted. Experience shows that there is positive advantage in introducing a documentation system that ensures that a) each page is uniquely identified to the system, section, page within section, issue number and date of origination: b) c) each section is identified as complete; insertions and deletions are clearly identified.

9.2

Principles of central documentation

The central documentation should contain all the information relating to the activities throughout the system life cycle. This information is permanently valid as it isupdated when each decision, achievement, modification, etc, is approved. To facilitate this updating, each item of information should normally only appear once.

9.3

Advice on documentation distribution

It is important to distinguish clearly between the total documentation collection, normally stored centrally, and the assembled subsets required by different departments and personnel. Subsets usually contain documents copied and compiled from different sections of the total documentation collection. A circulation list, based on an individual organization's requirements, should be drawn up for each document, noting the name or departmental code of the recipient of the documentation.

10
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Annex Program

A guidelines

documentation

(This annex forms part of the standard.)

A.1

Introduction

A.3
A.3.1

General items
Responsibilities

This annex gives guidance on the level of documentation required for program documentation. The level of detail required for component documentation is greater than that necessary for the other items in the body of this International Standard. The requirements have, therefore, been published in the form of an annex.

Provide addresses of organizations or persons responsible for development; operation; maintenance; further development of the program. Contractual items items,

A.2
A.2.1

Identification
A.3.2 Program name

Provide the title or name which identifies the program and a subtitle which briefly indicates its function.

Provide sufficient information about contractual including costs as applicable, for example

-- legal conditions such as copyright, privacy, security, etc. ;

A.2.2

Variants

modules supplied and corresponding purchase/rental price;
installation; training; maintenance; quality assurance. Scope and field of application

Describe the names used for identifying any co-existing variants of the program.

A.2.3

Version -

In addition to the program name and variant names, provide identification for the version that requires identifying among the several program versions that evolved after being modified over a period of time. The documentation shall reflect changes in the current version, and be kept up-to-date.

A.3.3

A.2.4

Date

A.3.3.1 Describe briefly the objectives which can be achieved by use of the program. A.3.3.2 Describe the functions of the program in a way that enables the user to decide whether, and within what limits, the program can be used. A.3.3.3 Describe the design philosophy and method, outstanding and distinguishing features of the program, planned future revisions, etc. A.3.4 Program Problem ? A.3.4.1.1 Problem description specifications

Provide the date of release of the original and the current version of the program.

A.2.5

History

For every modification, specify

-

variant name; version name; A.3.4.1

reference to the reason for and contents of modification; date of release; date of first use.

Present the problem to be solved by means of the program in a generally comprehensible form.

IS 13394 : 1992 IS0 6592 : 1985

A.3.4.1.2 State the

Supplementary theoretical

information principles, methods and literature

A.3.6
A.3.6.1
Specify

Operational
Language

specification

references.

the programming International

language Standard.

used, by reference Also, provide

to the

A.3.4.2

Problem

solution

appropriate variant,

the name,

version and supplier of the compiler

or interpreter.

A.3.4.2.1

Conventions

and terminology A.3.6.2 Software the names, requirements variants, versions (for example of other programs system, and rules which are for Provide needed or combinaespecially concoordinate used and their A.3.6.3 Hardware the requirements of the hardware with configuration to cor-

Provide details of the form of presentation to be used in the following example, cerning: systems, meanings, special interpretation prefixes, technical signs, tions applicable

parts of the documentation of characters/signs rounding-off,

to run the program with reference

operating

to the solution of the problem; accuracy, tables of abbreviations

subroutines),

to the corresponding

documenta-

tion of this software.

value ranges,

regulations

of data processing.

A.3.4.2.2

Solution

principles and algorithms of solution and algorithms presented in

Provide necessary

specifications documentation

Describe the methods connection organization

for running

the program,

references

with the specified functions of the program.

and with the structural

responding

and diagrams.

A.3.6.4 A.3.4.3 Functional specification

Mode

of operation for example batch, interactive,

Describe the mode of operation, realtime. A.3.4.3.1 Describe Function in detail, in non-technical language, all of the func-

A.3.7
Provide gram,

Application
typical

example
to help users understand the pro-

tions of the program and results produced.

with an explanation

of the data required examples including listings of data and results.

A.3.4.3.2

Characteristics

A.3.8
Provide quantitative performance information for typical examples, such as etc. data, level of accuracy, storage requirements,

Associated

documentation
to available documents (for example which pro-

Provide a list of references vide information guide, installation

on the program,

programmers'

A.3.4.3.3 Specify

Restrictions any restrictions on the use of the program.

guide), with references

to supplier and order

number of the documents.

A.3.4.3.4

Error handling by the program.

A.4 A.4.1

Technical Technical

documentation program description

Describe error handling

A.3.4.4 Describe facilities.

Data protection
the data

and security A.4.1.1 Terminology and conventions
including all names and and security functions and Describe the terms and conventions other internal data used within the program.

protection

A.3.5

Application

data description
data (for example input/outrelevant to

A.4.1.2 Describe

Program

structure of the program segments, common problem units (for example storage areas) in

Describe the application-oriented put data, their use. The data shall be described This data description with appropriate permanently

the organization modules,

stored data) with attributes

sub-programs, accordance

with the specified which

solution. for example structured their entry

according

to annex B. document,

The presentation by a tree-structure textual

can be made graphically, or by an appropriately the unit names,

diagram,

may be given in a separate

description,

shall contain

cross-references.

points, and interfaces,

as well as their inter-relationships.

12
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A.4.1.3

Program

listing

The procedures to be followed in operating the program should be provided in accordance with annex C. A.4.3.3 Messages

Provide a source program listing containing sufficiently detailed comments. A.4.2 Technical data description

Provide a list and description of all messages, including instructions for any necessary operational actions. A.4.4 A.4.4.1 Installation Installation and support

Provide a technical description of the data, including names, meanings, representations, contents, access, responsibilities, data security, and inter-relationships. This information should be provided for both application-oriented data (see A.3.5) and for other internal da?a. The data should be describtd according to annex B. This description may be contained in a separate document, in which case appropriate cross-references shall be made. A.4.3 A.4.3.1 Operation Control instructions

Provide technical information for the installation of the program. A.4.4.2 Adaptation

Provide sufficient information for users who need to adapt the program, for example for other environments, other uses. A.4.4.3 Test

Provide an appropriate commented list of all required operating system control instructions. A.4.3.2 Methods of operation

Describe the methods used to test the program, with input and expected results. A.4.4.4 Support

Describe or reference the methods to start, stop, pause, interrupt, and restart the program for the possible operation modes, including special operations and the operational rules for data files.

Provide additional technical information for the continuing support and development of the program.

13
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Annex Data documentation

B guidelines

(This annex forms part of the standard.)

6.1

Introduction

B.2.5.2

Validity

This annex gives guidance on the level of documentation required for data documentation. The level of detail required for component documentation is greater than that necessary for the other items in the body of this international Standard. The requirements have, therefore, been published in the form of an annex.

Detail the chronological validity of this documentation (from . . to . . .) and supply pertinent identification of the version and, if required, indication of the variant. (A VERSION characterizes the validity as a function of time; a VARIANT is a co-existing alternative. 1

B.3 B.3.1 6.2 Identification

Description Purpose

of the data

8.2.1

Technical

identification

Give the application-oriented description of the data and their purpose of application, differentiating with respect to other data as required.

Describe the technical identification of the data in program and database definitions. Other technical identifications required should also be indicated (see 8.4.2).

B.3.2

Descriptors

List the keywords, headings, and search words characterizing the application-oriented references in association with details of descriptor catalogues, as applicable.

8.2.2

Application-oriented

identification

8.3.3

Sensitivity

Describe the application-oriented identification for the data, for example in working instructions or application-oriented documents. Where synonyms have been used in application-oriented documents, these should also be specified here.

Indicate the sensitive properties of the data with respect to legal and operational requirements, for example data protection, confidentiality, classification (see clause B.6).

B.4 B.4.1

Representation Structure (not applicable to data elements)

8.2.3

Category

Define the data by naming or describing their category, for example data field, record, file, segment, page, database.

List the data objects forming the data entity being described, with their inter-relationships, for example position, errangement, repetition factor.

8.2.4

Status

8.4.2

Format

Describe the status of the data, for example test, production.

Describe the formats in which the data may occur. It may be sufficient to use such standard format descriptors as: PICTURE S9V99 COMPUTATIONAL to IS0 19691 (COBOL according

B.2.5

Applicability

of the documentation

8.251

Scope and field of application

blocked records of variable length (according to IS0 1~9)

Indicate the scope and field of application of the documentation concerned, for example the organizational unit of an enterprise, range of application.

If data occur in several formats, all forpats with their applications shall be indicated, for example program, file, database, print mask, input fields on screen, forms. If qualifying names are used, they should be stated.
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B.4.3
Indicate indicated

Size
the physical size of the data entity in a customary defined absolutely unit (for example or by means byte, word); of a formula.

B.5.5 or size may be
If required,

Encoding
applied to the data in the context of the codes, or reference

Describe any encoding application. a key list.

previously

Indicate the rules for allocating

upper and lower&mits

should be shown.

B.4.4
Indicate paper,

Medium

(not applicable
on which

to data elements)

B.6
B.6.1

Access
Authorization
such as organizational procedures units, agencies, together persons, with their

the medium magnetic

the data resides, for example

tape, data link, network. Authorities data processing and programs,

8.4.5

Compression
of compression applicable to the

legal basis and any other conditions sub-clauses.

are given in the following

Detail the type and method data.

B.6.1:1

Origination the authorities permitted to generate the data and to system.

B.4.6
Name

Code
the <ode used to represent the data, for example

Indicate introduce

it into the operational

data and information

IS0 7-bit code, logical level.

if it differs from the code defined

at a higher

B.6.1.2

Read

access permitted to read the data.

Indicate the authorities

8.4.7
Define

Character

set
set for the data, especially with

8.6.1.3

Amendment permitted to update or delete the con-

the valid character

Indicate the authorities tents of the data.

respect to special characters.

B.6.1.4

Communication permitted party to communicate without the contents List the

B.5
B.5.1

Content
Data type
of data, for example integer, alphabetic,

Indicate the auth&es of the data to authorities authorized

a third

restriction.

to receive such a communication.

Describe pointer,

the type vector,

B.6.2

Access

regulations
which regulate access to to their authoriza-

table,

clock time. Describe the measures or procedures the data by persons or programs according

8.5.2
Name

Units

of measurement
units of `measurement millimetre. applicable to the

tion.

the standard

data, for example

kilogram,

B.7
B.5.3 Range of values
For the data, for example of lower and

Responsiblities
Application-oriented
having

B.7.1

responsibility
application-oriented respon-

indicate the ranges of values defined by enumeraticn upper bounds, contained of valid values, or by reference

by indication

Indicate the authorities sibility for the data.

to the range of values of data

in the data entity being described.

B.7.2 B.5.4 Checking conditions
required for the data unless they character set, data type and concheck Indicate for example

Organizational

responsibility
having organizational responsibility for

Indicate the authorities

the data and its documentation. Detail the checking conditions are already described ditions connected character,

by format,

8.7.3

Technical

responsibility
having technical deve!opment. responsibility for the

range of values: also give further plausibility checks.

details on any checking

with other data entities,

the authorities

data. for example

software
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B.7.4

Custodial

responsibility

8.8.3

Encryption

Indicate the authorities and their locations where data is stored, for example the branch office of an enterprise.

Indicate the procedures for encrypting/decrypting the data, for example the relevant national standard.

B.9 B.8 Data security B.9.1

Associations Occurrence

8.8.1

Archiving

List the data entities which contain the data being described.

8.9.2
Detail the requirements for archiving the data, for example method, place, purpose, retention period, frequency.

Dependencies

List the other data entities on which this data is dependent and indicate the tvpe or name of this dependency relationship.

B.8.2

Recovery

8.9.3

Use

Indicate the procedures and the effort required to recover the archived data.

Provide or reference a list of athorities actually using the data. Also specify the type of access fin accordance with B.6.1).
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Annex Human procedure

C guidelines
1

documentation

(This annex forms part of the standard.

C.l

Introduction
on the level of documentation documentation. re-

C.3 C.3.1

General

items

This annex gives guidance

Responsibilities
of organizations or persons responsible for

quired for human procedures The level of detail this international been published required

Provide addresses for component The requirements documentation have, therefore, is greater than that necessary Standard. for the other items in the body of

-

development; distribution; training; modification and further development of the procedure.

in the form of an annex.

C.2 C.2.1

Identification C.3.2 Procedure name
Provide sufficient information about contractual items, inthe procedure in kluding costs as applicable, for example:

Contractual

items

Provide the title dr name used for identifying the related system and program which briefly indicates documentation, its function.

and a subtitle legal conditions such as copyright, privacy, security, etc. training; quality assurance; maintenance.

;

C.2.2 Variants
Describe the names used to identify any co-existing the program. variants of -

C.2.3

Version
to the procedure to distinguish For procedures instructions, name, and variant names, provide the most recent version from its for closely related to programs, version name.

C.3.3
C.3.3.1

Scope and field of application
Describe briefly the objectives which can be achieved the procedure.

In addition identification

by following

predecessors.

example operating

it is desirable to relate the pro-

C.3.3.2 use.

Describe

the functions

of the procedure which

in terms of indicate its

cedure version name to the program

the associated

software

and environment

C.2.4

Date
C.3.3.3 Describe or reference principles features; any philosophical, psychological, or ergonometric outstanding used in the design of the

Provide the date of release of the original and current versions of the procedure.

procedure;

planned future revisions, etc.

C.2.5

History
modification, specify

C.3.4
C.3.4.1

Procedure
Occasion,

specifications
frequency in which the procedure describe is applicable; prescribe if the

For every release of a procedure variant name; version name; reference

Describe the situations periodic, cycle; if conditional,

provide the cycle length,

and the position within the

the events which

use of the procedure. of the modiC.3.4.2 Conventions, terminology , followed in

to the reason for and content

fication

;

-

date of release; date of first use.

Provide details or a reference the naming used, etc. of this or related

to any conventions procedures,

any abbreviations
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C.3.4.3

Function

C.3.6.3

Hardware

requirements

Describe in detail all of the functions of the procedure, with particular reference to the materials and data required, the results recorded, the software and hardware utilized, the organizational units affected. C.3.4.4 Capabilities and resource requirements

Provide specifications for any computer hardware configuration involved in the procedure steps, and for any auxiliary or office equipment used with references to the corresponding documentation.

C.3.6.4

Supplies

Provide quantitative information concerning typical volume and speed of processing, usage of resources such as computer and peripheral hardware, supplies, office equipment, space, etc. C.3.4.5 Restrictions 8nd exceptions

Provide information concerning the procedure's requirements for such supplies as computer media, stationery items, etc.

C.3.6.5

Timing constraints

Describe any restrictions on the use of the procedure, or situations in which it is not applicable; preferably, include a reference to alternate procedures. C.3.4.6 Personnel

Describe any scheduling requirements, any constraints on speed of processing, or any limitations on the occasions calling for the use of the procedure.

C.3.7

Application

example

Describe the person or persons who will follow the procedure, in terms of their function within the organization, for example billing clerk, computer operator. C.3.4.7 Data protection, security, and privacy concerns

Provide typical examples to help users understand the procedure, including illustrations of typical data and results.

C.3.8

Associated

documentation

Describe briefly or reference any policies relevant to the protection of the data or the procedures themselves from unauthorized access.

C.3.5

Application

data description

Provide a list of references to available documentation concerning the system of which the procedure is a part, the software and hardware involved, any related procedures, and any relevant organizational information. Also provide information concerning the location of this documentation, and any procedures necessary for its procurement.

Describe the application-oriented data required by, processed by, and generated by the procedure, with attributes relevant to their use in the procedure. The data shall be described in accordance with annex 6.

C.4
C.4.1

Technical Technical

documentation procedure description

The data description may be given in a separate document, with appropriate cross-references.

C.4.1.1

Terminology

and conventions

C.3.6
C.3.6.1

Environment

specification

Personnel skills

Define or reference definitions for any technical or specialized terms used, and for any abbreviations. Provide or reference a description of the nomenclature conventions used in naming system components (programs, procedures, data entities).

Specify any special skills or training required by the person following the procedure. C.3.6.2

C.4.1.2

Procedure

structure

Software requirements

Identify, by name, variant, version, any software involved in the usage of the procedure, and provide a reference to its documentation. For a procedure detailing the provision of input data to a program, make special reference to the data validation and error handling features of the program; for a procedure detailing the operation of a program, make special reference to the operational specifications of the program; for a procedure detailing the interpretation, control, or distribution of the output from a program, make special reference to the application and technical data descriptions, and messages.

For composite procedures, which provide instructions for several occasions, or which contain conditional steps, describe the organization of the procedure, preferably graphically.

C.4.2

Procedure

structure

Define the procedure to be followed as a series of numbered imperative instructions, beginning wkh any necessary collection of materials or information, and proceeding in chronological sequence to final disposition of any results of the procedure.
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Distinguish carefully between instructions, for example worded in the imperative and explanatory material, for example worded passively, by typographical or other means. Where steps are conditional or repetitive, arrange them so that the control information precedes the procedures it affects, and indicate the range of the control by step numbers both at the beginning of the affected steps and at their conclusion. Tailor the language of the procedure steps to the skill set and training level of the person who will follow the procedure.

C.4.4.2

Testing

Describe the methods used to test the procedure, with sample data processed and results.

C.4.4.3 Detail

Training

a) the provisions made for training the person who will initially and subsequently use the procedure; b) the persons or organizations responsible;

C.4.3

Technical

data description

Provide a technical description of any data involved in the procedure, including names, meanings, representations, media, contents, access methods, structure, responsibilities, data security provisions, and inter-relationships. This information should be provided both for the application-oriented data (see C.3.5) and for any data internal to the procedure, for example control tallies, tables. The data should be described in accordance with annex B. This description may be contained in a separate document, in which case appropriate cross-references are required.

c) the typical duration of training, the productivity "learning curve", etc. C.4.4.4 Refinement

Describe or reference the means by which persons following the procedure, or other persons involved, may contribute suggestions for its improvement. C.4.4.5 Adaptation

C.4.4
C.4.4.1

Installation
Distribution

and support
and filing

Provide any relevant suggestions for adapting the procedure for other uses or environments. C.4.4.6 Support

Provide any necessary information about the means of distribution and procedures for filing or posting the procedure and its associated documentation.

Provide any additional technical information relevant to the continuing support and development of the procedure.
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